Inside Macintosh: QuickDraw GX Objects /

Chapter 5 - Ink Objects / Using Ink Objects

Creating and Manipulating Ink Objects

This section describes how you can create and interact with ink objects as whole entities--to create, dispose of, copy, compare, and clone them. Manipulating the individual properties of ink objects is described under "Manipulating Ink Object Properties" beginning on page 5-40.

Creating and Disposing of Ink Objects

QuickDraw GX provides the GXNewInk function to allow you to create a new ink object. You can also create a new ink object by copying an existing one with the GXCopyToInk function. Once you have created an ink object, you can customize its features using the techniques described in the section "Manipulating Ink Object Properties" beginning on page 5-40.

To delete your application's reference to an ink object, call the GXDisposeInk function, which may or may not actually release the memory allocated for that ink object, depending on the ink's owner count. The GXDisposeInk function decreases the ink object's owner count by 1; if that brings the owner count to zero, the ink is completely deleted and its memory released. See "Manipulating an Ink Object's Owner Count" beginning on page 5-41.

The following code fragment creates three ink objects in turn, gives each a color, assigns each to a shape (windowShape1, windowShape2, and windowShape3), adds each to a picture shape (gOurHouse), and then disposes of each ink reference because it is no longer needed. The code calls the library function SetInkCommonColor to assign colors to the individual ink objects.

gxInk redInk = GXNewInk();
SetInkCommonColor(redInk, red);  
GXSetPictureParts(gOurHouse, 0, 0, 1, &windowShape1, 
                  nil, &redInk, nil);
GXDisposeInk(redInk);

gxInk grayInk = GXNewInk();
SetInkCommonColor(grayInk, gxGray);  
GXSetPictureParts(gOurHouse, 0, 0, 1, &windowShape2, 
                  nil, &grayInk, nil);
GXDisposeInk(grayInk);

gxInk turquoiseInk = GXNewInk();
SetInkCommonColor(turquoiseInk, turquoise);  
GXSetPictureParts(gOurHouse, 0, 0, 1, &windowShape3, 
                  nil, &turquoiseInk, nil);
GXDisposeInk(turquoiseInk);

The GXNewInk function is described on page 5-56. The GXDisposeInk function is described on page 5-57. The GXSetPictureParts function is described in the picture shapes chapter of Inside Macintosh: QuickDraw GX Graphics.

Copying, Comparing, and Cloning Ink Objects

You can use the GXCopyToInk function to copy information from one ink object to another or to create a new copy of an ink object.

You can test if two ink-object references refer to the same ink object by simply testing the references for equality. You can also compare two different ink objects for equality with the GXEqualInk function. For two ink objects to be equal, their attributes, colors, color spaces, and transfer modes must have identical values, although their general object properties (owner count and tag list) do not need to be identical. Ink object copies created with the GXCopyToInk function are always equal to the ink from which they were copied.

The following code fragment effectively changes the default ink for a certain shape type. It makes a copy (tempInk) of the default ink object, modifies its color and transfer mode, and then assigns the modified copy to the default shape object for line shapes. After it makes the assignment, the code disposes of tempInk. The code makes use of the library functions SetInkCommonColor and SetInkCommonTransfer to set the ink's color and transfer mode.

tempInk = GXCopyToInk(nil,
                  GXGetShapeInk(GXGetDefaultShape(gxLineType)));
SetInkCommonColor(tempInk, gxBlack);
SetInkCommonTransfer(tempInk, xorMode);
GXSetShapeInk(GXGetDefaultShape(gxLineType),tempInk);
GXDisposeInk(tempInk);

In certain circumstances, you may want to copy a reference to an ink object without actually copying the ink object. For example, you may want two variables to refer to the same ink object, so that editing one of them affects both. This is called cloning an ink, rather than copying an ink. You can use the GXCloneInk function to clone an ink object.

Functionally, GXCloneInk does nothing more than increase the owner count of an ink object. For more information about cloning objects, see the chapter "Introduction to Objects" in this book. For information on manipulating ink owner counts, see the section "Manipulating an Ink Object's Owner Count" beginning on page 5-41 of this chapter.

The GXCopyToInk function is described on page 5-58. The GXEqualInk function is described on page 5-59. The GXCloneInk function is described on page 5-59.

Loading and Unloading Ink Objects

Although you rarely need to, you can influence memory-allocation decisions involving objects that you have created. If your application needs to have an ink object in memory, you can force QuickDraw GX to load it into memory. When your application no longer needs the ink object in a loaded state, you can instruct QuickDraw GX to unload it.

You call the GXLoadInk function to make sure that an ink object is in memory; if necessary, QuickDraw GX brings the object into memory from an unloaded state. You can call the GXUnloadInk function to instruct QuickDraw GX that it is free to unload the ink object at any time. These functions are described in the memory management chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.